CHAPTER 2 BTRIEVE ARCHITECTURE If you are new to Btrieve, you should read this chapter before installing and configuring Btrieve. It provides an introduction to the Btrieve components and how they work with Btrieve applications. If you have used Btrieve before, you may want to skip to the example diagrams of Btrieve architecture, which begin in "Examples of Btrieve Architecture." This chapter discusses the following topics: o Components of Btrieve o Btrieve Applications on a Server o Btrieve Applications on a Workstation o Examples of Btrieve Architecture Components of Btrieve The major components of server-based Btrieve are as follows: o Server-Based Record Manager o Communications Programs o Workstation Requesters o Btrieve Utilities Server-Based Record Manager Btrieve's server-based Record Manager (BTRIEVE.NLM) must be loaded at every server that accesses Btrieve files. The Btrieve NLM consists of a library of Btrieve functions and handles these tasks: o Performs disk I/O for Btrieve files at the server where it resides o Provides concurrency and integrity controls on the server where it resides o Logs all Btrieve requests that result in changes to a file (if logging is enabled for that file) Communications Programs Btrieve provides the following communications programs: o Btrieve Message Router (BROUTER.NLM) o BSPXCOM.NLM o BSPXSTUB.NLM o RSPXSTUB.NLM Btrieve Message Router The Btrieve Message Router (BROUTER.NLM) handles outgoing requests from your server to a remote server. The Message Router allows a Btrieve application running as an NLM on the server to communicate with remote servers on which other Btrieve NLMs are loaded. Also, the Message Router maintains transaction concurrency controls during transactions involving Btrieve files on more than one server. If your server-based application needs to access files on another server, you must have the Message Router loaded on your server. When you request files from another server, the Message Router sends that request to BSPXCOM (discussed in the next section) on the remote server. BSPXCOM routes your request to the Btrieve NLM on that server and then sends the response back to the Message Router on your server. BSPXCOM BSPXCOM handles incoming requests to the Btrieve NLM from a remote source. The remote source could be a Requester at a workstation or the Message Router on another server. BSPXCOM must be loaded on servers that support remote requests. If no workstations or other servers make requests to the Btrieve NLM, you may not want to have BSPXCOM loaded at your server. For example, assume your Btrieve NLM receives calls only from other NLMs running at your server. In this case, you could choose not to load BSPXCOM for security reasons. (Not loading BSPXCOM allows you to restrict applications other than the ones on your server from accessing your Btrieve files.) BSPXSTUB and RSPXSTUB If you do not load BSPXCOM and want to use the Btrieve Monitor utility, you must load either the BSPXSTUB or RSPXSTUB communications module. These modules resolve external references for the Monitor utility that BSPXCOM would otherwise resolve. Use the following guidelines to determine whether you need BSPXSTUB or RSPXSTUB: o If you want to use the Btrieve Monitor utility but do not want to load BSPXCOM, and the NLMs on the server are accessing Btrieve files only on the local server, load BSPXSTUB at the server. o If you want to use the Btrieve Monitor utility to monitor outgoing requests generated by the Message Router to another server and you do not want to load BSPXCOM, load RSPXSTUB instead of BSPXSTUB at the server. NOTE: The Btrieve Monitor utility's Communication Statistics option (discussed in Chapter 5, "Using Btrieve Utilities") displays SPX communication statistics. The communications module you load affects the statistics displayed. For example, if you load BSPXCOM, you see incoming and outgoing SPX statistics for BSPXCOM. If you load BSPXSTUB, you see all zeros. If you load RSPXSTUB, you see incoming and outgoing SPX communication statistics from the Message Router. Workstation Requesters Btrieve provides the following Requesters for applications running on the workstation: o BREQUEST.EXE - DOS Requester o BTRCALLS.DLL - OS/2 Requester o WBTRCALL.DLL - Windows Requester NOTE: Btrieve now provides a requester for the UnixWare environment. For information about this new UnixWare Requester, please refer to the Readme file that accompanies this release. A Btrieve Requester must be loaded at each workstation that makes Btrieve requests. The Requester receives Btrieve requests from an application and relays them via BSPXCOM to the Btrieve NLM running on the server. After the Btrieve NLM processes the request, BSPXCOM sends the results back to the Requester, which forwards them to the application. For information on starting the Requester in each operating environment, refer to Chapter 4, "Configuring and Using the Requesters." Btrieve Utilities Btrieve provides the following utilities for Btrieve file management: o Setup and Rebuild utilities (BSETUP.NLM and BREBUILD.NLM) - You can use the Setup utility to change the settings of Btrieve configuration options, and you can use the Rebuild utility to convert existing Btrieve v5.x files to Btrieve v6.x format. (As "Rebuilding Existing Btrieve Files" in Chapter 3 explains, you can choose to run the Rebuild utility from within the Setup utility.) o Monitor utility (BTRMON.NLM) - You can use this utility to monitor the activity of Btrieve at the server. o Maintenance utility (BUTIL.NLM) - You can use this utility to import and export Btrieve data and transfer data from one Btrieve file to another. This utility also lets you enable and disable continuous operation on your Btrieve files. o Roll Forward utilities (BROLLFWD.EXE for DOS, PBROLL.EXE for OS/2, and WBROLL.EXE for Windows) - The Roll Forward utilities recover changes made to a Btrieve file between the time of the last backup and a system failure. The Roll Forward utilities are for workstation use only. For more information about the Btrieve Setup and Rebuild utilities, refer to Chapter 3, "Installing and Configuring Btrieve." For information about the Btrieve Monitor, Maintenance, and Roll Forward utilities, refer to Chapter 5, "Using Btrieve Utilities." Btrieve Applications on a Server A Btrieve application running on a server (that is, an NLM) can access data on the local server or on a remote server, as follows: o Accessing Local Data - The application makes a request for Btrieve data that is located on the local server. The request is processed by the Btrieve NLM on the server where the Btrieve request originated. o Accessing Remote Data - The application makes a request for Btrieve data that is located on a remote server. The request is processed by the Btrieve NLM on the remote server. The following sections describe the events that occur when your NLM application makes local and remote requests. Server Application Accessing Local Data When an application running on a server is accessing data on that server, the Btrieve NLM must be loaded on that server. The following steps describe accessing data on the local server: 1. The application sends a request to the Btrieve NLM. If the Message Router is not loaded, the call is made directly to the exported entry point of Btrieve on the local server. If the Message Router is loaded, it relays the call to Btrieve on the local server. 2. Btrieve processes the request using the Btrieve library of function calls. 3. If the Message Router is not loaded, Btrieve returns the appropriate data and status code directly to the calling application. If the Message Router is loaded, Btrieve returns the data and status code to the Message Router; the Message Router then transports the data and status code to the calling application. Server Application Accessing Remote Data When an application running on a local server is accessing data on a remote server, the Message Router and the Btrieve NLM must be loaded on the local server, and BSPXCOM and the Btrieve NLM must be loaded on the remote server. The following steps describe accessing data on a remote server: 1. The application (running on the local server) makes a request to access a Btrieve file located on a remote server. 2. The Message Router on the local server detects that the request is for a remote Btrieve file and sends the request to BSPXCOM on the remote server. 3. BSPXCOM (remote) relays the request to the Btrieve NLM (remote) by making Btrieve function calls. 4. The Btrieve NLM (remote) returns the appropriate data and status code to BSPXCOM (remote). 5. BSPXCOM (remote) returns the data and status code to (local), where the Btrieve request originated. 6. The Message Router (local) returns the results to the calling application (local). The Message Router places the results in the application's memory at the location designated by the parameters passed to Btrieve in the function call. Control then returns to the calling application. Btrieve Applications on a Workstation A Btrieve application running on a workstation can access local, remote, or local and remote data as follows: o Accessing Local Data - The application makes a request for Btrieve data that is located on the workstation. The request is processed by client-based Btrieve on the same workstation where the request originated. o Accessing Remote Data - The application makes a request for Btrieve data that is located on a remote server. The request is sent to the Requester, which passes the request to the Btrieve NLM on the remote server. The Btrieve NLM processes the request. o Accessing Local and Remote Data - The application makes a request for Btrieve data that is located on the local workstation or a remote server. The request for data is intercepted by the Requester. The Requester determines if the data is on the workstation or a remote server, and routes the appropriate request to client-based Btrieve on the workstation or the Btrieve NLM on a remote server. The following sections explain what happens when your workstation application makes local and remote requests. Workstation Application Accessing Local Data When an application is accessing local data on the workstation, client-based Btrieve must be loaded on the workstation. The following steps describe accessing data on the workstation: 1. The application makes a Btrieve request using a function call. 2. The interface code that you link with your application makes the call to client-based Btrieve. (Novell provides the interface code.) In a Windows or OS/2 environment, you must import the function definition. 3. Client-based Btrieve processes the request using the Btrieve library of function calls. 4. Client-based Btrieve returns the appropriate data and status code directly to the calling application. Workstation Application Accessing Remote Data When an application is accessing data on a remote server from a workstation, the Requester must be loaded on the workstation, and BSPXCOM and the Btrieve NLM must be loaded on the server. The following steps describe accessing data on a server from an application running on the workstation: 1. The application makes a Btrieve request using a function call. 2. The interface code that you link with your application makes the call to the Requester. (Novell provides the interface code.) In a Windows or OS/2 environment, you must import the function definition. 3. The Requester packages the request into a network message and routes the message to BSPXCOM on the remote server. 4. BSPXCOM receives the network message, validates the parameters, and then executes the request by making function calls to the Btrieve NLM. 5. The Btrieve NLM processes the request and returns the results to BSPXCOM. 6. BSPXCOM forwards the results to the Requester at the workstation. 7. The Requester returns the appropriate data and status code to the parameter variables in your applicationŐs memory and returns control to your application. Workstation Application Accessing Local and Remote Data When an application is accessing local and remote data from a workstation, the Requester and client-based Btrieve must be loaded on the workstation, and BSPXCOM and NetWare Btrieve must be loaded on the server. The following steps describe accessing local and remote data from an application running on the workstation: 1. The application makes a Btrieve request using a function call. 2. The interface code that you link with your application makes the call to the Requester. (Novell provides the interface code.) In a Windows or OS/2 environment, you must import the function definition. 3. The Requester determines whether the server or the workstation should receive the request. 4. This step varies, depending on whether the requested data is on the workstation or on a remote server: o If the requested data is on the workstation, the Requester sends the request directly to client-based Btrieve. Btrieve processes the request using the Btrieve library of function calls. Client-based Btrieve returns the appropriate data and status code directly to the calling application. o If the requested data is on a remote server, the Requester packages the request into a network message and routes the message to BSPXCOM on that server. BSPXCOM receives the network message, validates the parameters, and then executes the request by making function calls to the Btrieve NLM. The Btrieve NLM processes the request and returns the results to BSPXCOM. BSPXCOM forwards the results to the Requester at the workstation. The Requester returns the data and status code to the calling application. Examples of Btrieve Architecture The diagrams in this section demonstrate how different Btrieve applications require different Btrieve components. This section discusses the following examples: o Server Application Using the Btrieve NLM o Server Application Using the Btrieve Message Router o Server Application Using the Btrieve Message Router and BSPXCOM o Workstation Application Using the Requester and Client-Based Btrieve o Server Application Using RSPXSTUB o Server Application Using BSPXSTUB o Server Application Using NetWare SQL The following examples indicate remote requests with dashed lines and local requests with solid lines. Server Application Using the Btrieve NLM Figure 2-1 shows an application accessing Btrieve data on the local server. The application is making local requests to the local Btrieve NLM. Note that BSPXCOM is not loaded because there are no incoming requests to the Btrieve NLM from another server or workstation. Figure 2-1 Server Application Using the Btrieve NLM NLM Application | ^ | | v | Btrieve NLM | ^ | | v | NetWare | ^ | | Server | | --------|------|--------- v | File System Server Application Using the Btrieve Message Router Figure 2-2 shows an application running on Server A. It is making requests to the local Btrieve NLM (Server A) and to a remote Btrieve NLM (Server B) via the Btrieve Message Router. The Message Router handles outgoing requests from Server A to the remote Server B. The Message Router must be loaded on Server A in order to send the requests to Server B. BSPXCOM must be loaded on Server B to accept incoming requests from the Message Router. Figure 2-2 Server Application Using the Btrieve Message Router NLM Application BSPXCOM | ^ +---------------- | ^ | | | +----------> | | v | | | v | Btrieve Message <-----+ | Btrieve NLM Router | | ^ | ^---------------+ | | v | v | Btrieve NLM NetWare | ^ | ^ | | | | Server B v | | | NetWare ----------|-----|---------- | ^ v | Server A | | File System | | ----------|-----|------ v | File System Server Application Using the Btrieve Message Router and BSPXCOM Figure 2-3 illustrates a server application that requires both the Btrieve Message Router and BSPXCOM. In Figure 2-3, the Message Router handles outgoing requests from the local server to a remote server. BSPXCOM handles incoming requests to the Btrieve NLM from a remote source (either a Requester at a workstation or the Message Router on another server). The server is supporting incoming requests from a remote source and outgoing requests to a remote server. Figure 2-3 Server Application Using the Btrieve Message Router and BSPXCOM NLM Application | ^ | | v | +-->Btrieve Message Router<===>Outgoing requests | | ^ to/from a remote | | | server Incoming requests from/to | v | a remote source <====|==> BSPXCOM | | ^ | | | | v | +--> Btrieve NLM | ^ | | v | NetWare | ^ Server | | | | ----------|-----|------ v | File System Workstation Application Using the Requester and Client-Based Btrieve Figure 2-4 shows an application running on a workstation. The application is accessing local data via client-based Btrieve and remote data via the Requester. The Requester passes requests for local data to client-based Btrieve. In this environment, the Requester on the workstation performs the same function as the Message Router in Figure 2-3. BSPXCOM handles incoming requests to the Btrieve NLM from a remote source. Figure 2-4 Workstation Application Using the Requester and Client-Based Btrieve Workstation Application Linked with Interface Code +-------------> BSPXCOM | ^ | +----------- | ^ | | | | | | v | | | v | Btrieve ----+ | Btrieve NLM Requester <------+ | ^ | ^ | | | | v | v | NetWare Client-Base d | ^ Btrieve | | | ^ | | Server | | ----|--|--------- v | v | Client OS File System | ^ | | | | Workstation -----|---|-------------- v | File System Server Application Using RSPXSTUB Figure 2-5 shows an application running on Server A. It is accessing both local and remote data. The Btrieve Monitor utility (BTRMON.NLM) is running on Server A. To run the Monitor utility, Server A must have either BSPXCOM, BSPXSTUB, or RSPXSTUB loaded. Since the Btrieve NLM on Server A is not accepting any incoming requests from workstations or remote servers, BSPXCOM is not loaded. Instead, RSPXSTUB is loaded on Server A; it allows users to see the Btrieve Message RouterŐs communication statistics through the Monitor utility's Communication Statistics option. Figure 2-5 Server Application Using RSPXSTUB +----->NLM Application | | | | +-->RSPXSTUB | BTRMON<--+ | | | | | | | +-->Btrieve | +----->Message Router <====|=================> BSPXCOM | ^ | | ^ | | | | | | | | v | | | | Btrieve NLM v | | | ^ Btrieve NLM <------+ | | | ^ v | | | NetWare v | | ^ NetWare | | | ^ | | Server B Server A | | ----|---|---------- | | v | ----------|-----|------ File System v | File System Server Application Using BSPXSTUB Figure 2-6 shows an application running on the server. The application is accessing local data. The Btrieve Monitor utility (BTRMON.NLM) is also running on the server. Since the Btrieve NLM is not accepting any incoming requests, BSPXCOM is not loaded. However, to run the Monitor utility, the server must have either BSPXCOM, BSPXSTUB, or RSPXSTUB loaded. Since the Btrieve Message Router is not loaded, BSPXSTUB is the appropriate communications module to have loaded. When BSPXSTUB is loaded, the Communication Statistics option in the Btrieve Monitor utility shows zeros for the SPX statistics, since there is no SPX activity. Figure 2-6 Server Application Using BSPXSTUB +------------>NLM Application | | | | RSPXSTUB / BTRMON | ^ | | | | | | v +-------------> Btrieve NLM | ^ | | v | NetWare | ^ Server | | | | ----------|--|------ v | File System Server Application Using NetWare SQL Figure 2-7 shows NetWare SQL running on Server A. Since NetWare SQL needs to access data on both Server A and Server B, the Btrieve Message Router is loaded on Server A. In addition, NSSPXCOM is loaded on Server A because NetWare SQL is also responding to requests from a NetWare SQL Requester running on a remote workstation. (NSSPXCOM provides the same functionality for NetWare SQL as BSPXCOM provides for Btrieve.) Figure 2-7 Server Application Using NetWare SQL NSSPXCOM<=============> Incoming requests from/to | ^ a remote source | | v | NetWare SQL | ^ | | v | Btrieve Message<========================>BSPXCOM Router | ^ | ^ | | | | v | | | Btrieve NLM v | | ^ Btrieve NLM | | | ^ v | | | NetWare v | | ^ NetWare | | | ^ | | Server B Server A | | ----|---|---------- | | v | ----------|-----|------ File System v | File System